home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / 051-060 / amok52 / gadgeted / gadgeted.dok < prev    next >
Text File  |  1993-11-04  |  18KB  |  458 lines
  1. ----------------------------------------------------------------------
  2.                    Dokumentation zu GadgetEd V1.0
  3. ----------------------------------------------------------------------
  4.  
  5. Copyright:
  6. ----------
  7. Dieses Projekt ist Public Domain und darf frei kopiert werden, solange
  8. die Vollständigkeit des Projekts (s.u.) und mein Name im Programm
  9. erhalten bleibt.
  10. Eine kommerzielle Vermarktung des Projekts ist nur mit ausdrücklicher
  11. Genehmigung des Autors erlaubt. Dies gilt ebenfalls für eine
  12. kommerzielle Nutzung des mit diesem Projekt erstellten Modula2-Source-
  13. codes (d.h., daß Teile eines kommerziell vertriebenen Programms mit
  14. diesem Projekt erstellt werden).
  15. Ausdrücklich erlaubt ist, die mit diesem Projekt erstellten Module in
  16. privat genutzten oder nicht kommerziellen, frei kopierbaren Programmen
  17. (Public Domain, Shareware mit geringer Gebühr) einzusetzen.
  18.  
  19. GadgetEd V1.0
  20. ©1990 Hubert Bildstein
  21. alle Rechte vorbehalten
  22.  
  23. Autor: Hubert Bildstein
  24.        Gehenbühlstr. 5
  25.        W7000 Stuttgart 31
  26.        Germany
  27.        Tel.: 0711/83 18 32
  28.  
  29. Umfang des Projektes:
  30. ---------------------
  31. Das Projekt GadgetEd besteht aus folgenden Modulen:
  32. - GadgetEd    (Hauptprogramm)
  33. - Requester
  34. - MoveAndSet
  35. - Gadgets     (Auch unabhängig von GadgetEd gut verwendbar)
  36. - Io
  37. - CreateModule
  38. - TextWindows
  39. - Message
  40. - FileNames1  (Enthält Ersatz für FileNames.GetExtension)
  41. - DataStruct  (Datenstrukturen, nur DEFINITION-Module)
  42. - ARPFileReq  (Amok#31 [B. Preusing])
  43. - Menu        (Modul-Gerüst erstellt mit Menugenerator Amok#37 [S. Kraus])
  44.  
  45. - Test1       (Testprogramm 1)
  46. - Req1        (Gadget-Struktur zu Test1)
  47. - Test2       (Testprogramm 2)
  48. - Req2        (Gadget-Struktur zu Test2)
  49.  
  50. Das Projekt benötigt die ARP.library in LIBS: und ca. 10kB Stack.
  51.  
  52. --------------------------
  53. Beschreibung des Projekts:
  54. --------------------------
  55. GadgetEd erlaubt es, ein Fenster mit einer Gadget-Struktur zu versehen.
  56. Diese Struktur kann aus Boolean-, toggleSelect-, String-, Integer- und
  57. 1- oder 2-dimensionalen Proportional-Gadgets bestehen. Jedem Gadget kann
  58. ein Text und ein Rahmen zugewiesen werden. Die Gadgets können frei im
  59. Editor-Fenster positioniert und auch nachträglich verändert werden.
  60. Jede Funktion kann über Menü oder eine Tastenkombination angewählt
  61. werden.
  62. Das Fenster kann ebenfalls verschoben und verkleinert/vergrößert werden.
  63. Die gesamte Struktur samt Fenstergröße und -position kann zum späteren
  64. Weiterbearbeiten abgespeichert und wieder eingeladen werden.
  65. Damit mit der Struktur irgendetwas anzufangen ist, kann man den Modula-
  66. Quellcode, der diese Struktur aufbaut, erstellen lassen und in eigene
  67. Programme einfügen.
  68.  
  69. Die Anzahl der Gadgets ist auf 50 begrenzt. (Konstante in GadgetEd.mod)
  70.  
  71.  
  72. Aufruf:
  73. -------
  74. Von der Workbench: Doppelklick des GadgetEd-Icons.
  75. Aus dem CLI:       GadgetEd [Filename]
  76. "Filename" ist eine gespeicherte Menu-Struktur. Falls keine Extension
  77. angegeben wird, wird ".ged" als Default verwendet.
  78.  
  79.  
  80. Bedienung:
  81. ----------
  82. Nach dem Start erscheint ein kleines Window mit Copyright-Vermerk. Es
  83. verschwindet nach ca. 7 Sekunden oder durch Anklicken des Windows oder
  84. des Close-Gadgets.
  85.  
  86. Mit Drücken der HELP-Taste erscheint ein Window, in dem die Funktions-
  87. tasten aufgeführt sind.
  88.  
  89. In der Titelleiste des Screens und des Windows steht im Normalfall der
  90. Programmname und der Filename der gerade zu bearbeitenden Struktur.
  91. Alle sonstigen Meldungen (z.B. Disk-Status, was gerade bearbeitet wird)
  92. erscheinen ebenfalls in der Titelleiste.
  93.  
  94. Durch Anklicken des Windows wird das ganze Fenster neu gezeichnet.
  95.  
  96. Die einzelnen Funktionen werden über das Menü oder durch Tastenkombi-
  97. nationen angewählt:
  98.  
  99. PROJECT-Menü:
  100. -------------
  101. - Load: Laden einer Gadget-Struktur über den ARP-FileRequester.
  102.   Abkürzung: <RAMIGA>L    (= Rechte Amiga-Taste gleichzeitig mit L)
  103.  
  104. - Save: Speichern der aktuellen Gadget-Struktur unter dem aktuellen
  105.         Filenamen. Falls kein Filename existiert, wird auf "SaveAs"
  106.         umgeschaltet.
  107.   Abkürzung: <RAMIGA>S
  108.  
  109. - SaveAs: Speichern der aktuellen Gadget-Struktur unter einem neuen
  110.           Namen über den ARP-FileRequester.
  111.   Abkürzung: <RAMIGA>A
  112.  
  113. - New: Löschen der aktuellen Gadget-Struktur.
  114.   Abkürzung: <RAMIGA>N
  115.  
  116. - MakeModule: Erstellen des Modula-Quellcodes der aktuellen Struktur.
  117.               Es wird nach dem Namen des zu erstellenden Moduls gefragt.
  118.               Der Name sollte ohne Extension angegeben werden. Es ist
  119.               zu beachten, daß der Name (ohne Extension und ohne Pfad)
  120.               Bestandteil des Modul- und der Prozedurnamen wird und
  121.               somit ein gültiger Bezeichner sein muß (keine Sonder-
  122.               zeichen, Groß-/Kleinschreibung wird übernommen).
  123.               Um die Funktion abzubrechen, klickt man das Close-Gadget
  124.               des Windows an, ansonsten betätigt man die RETURN-Taste
  125.               im aktiven String-Gadget, um das Modul zu erstellen.
  126.   Abkürzung: <RAMIGA>M
  127.  
  128. - QUIT : Beenden des Programms.
  129.   Abkürzung: ESC
  130.  
  131.  
  132. EDIT-Menü:
  133. ----------
  134. Nach Auswahl einer der Punkte dieses Menüs muß das Gadget, auf das sich
  135. die Operation beziehen soll, angeklickt werden. Soll die Funktion nicht
  136. ausgeführt werden, klickt man einen beliebigen Punkt des Windows, der
  137. nicht von einem Gadgets belegt ist, an.
  138.  
  139. - Delete: Löschen eines Gadgets.
  140.   Abkürzung: F1
  141.  
  142. - Move: Verschieben eines Gadgets. Das Gadget kann nicht aus dem Fenster
  143.         herausbewegt werden.
  144.   Abkürzung: F2
  145.  
  146. - Copy: Kopieren eines Gadgets.
  147.   Abkürzung: F3
  148.  
  149. - Size: Verändern der Größe eines Gadgets. Der Mauszeiger muß immer auf
  150.         der rechten unteren Ecke des Gadgets stehen, die linke obere
  151.         Ecke bleibt immer fest.
  152.   Abkürzung: F4
  153.  
  154.  
  155. GADGETS-Menü:
  156. -------------
  157. - Boolean
  158.   - Normal: Erstellen eines "normalen" Boolean-Gadgets. Festlegen von
  159.             Größe und Position durch Drücken der linken Maustaste
  160.             (erster  Eckpunkt) und deren Wiederloslassen (zweiter Eck-
  161.             punkt). Zu kleine Gadgets werden nicht erstellt.
  162.             Ein "normales" Boolean-Gadget löst durch sein Anwählen eine
  163.             Aktion aus (z.B OK/CANCEL des System-Requesters).
  164.   Abkürzung: B
  165.  
  166.   - toggleSelect: Erstellen eines toggleSelect-Boolean-Gadgets. Größe
  167.                   und Position wird wie bei dem normalen Boolean-Gadget
  168.                   festegelegt.
  169.                   Ein toggleSelect ändert durch das Anwählen seinen
  170.                   Zustand von "An" in "Aus" und umgekehrt (z.B. das
  171.                   CLI-Gadget in den Preferences).
  172.   Abkürzung: T
  173.  
  174. - String
  175.   - Normal: Erstellen eines "normalen" String-Gadgets.
  176.             Zuerst muß die Breite des Gadgets festgelegt werden. Dies
  177.             geschieht wie bei den Boolean-Gadgets, indem man zwei Eck-
  178.             punkte auswählt. Die Höhe wird dann automatisch auf 8
  179.             Pixel (=Höhe eines Zeichens) gesetzt. Danach positioniert
  180.             man das Rechteck mit der gewählten Breite und festen Höhe
  181.             endgültig im Window.
  182.             Mit einem String-Gadget kann man beliebige Texte abfragen.
  183.   Abkürzung: S
  184.  
  185.   - Integer: Integer-String-Gadgets unterscheiden sich von normalen
  186.              String-Gadgets dadurch, daß als Eingabe nur Ziffern
  187.              und +/- möglich sind und die Eingabelänge durch den
  188.              Bereich von LONGINT begrenzt ist.
  189.   Abkürzung: I
  190.   Die Bündigkeit der String-Gadgets (Links, Zentriert,Rechts) wird im
  191.   Menü ATTRIBUTES festgelegt.
  192.  
  193. Der Rahmen eines String- und Boolean-Gadgets wird ebenfalls im Menü
  194. ATTRIBUTES festgelegt.
  195.  
  196. - Proportional
  197.   - Horiz: Erstellen eines horizontalen Proportional-Gadgets. Position
  198.            und Größe werden wie bei Boolean-Gadgets festgelegt.
  199.            Nach der Positionierung erscheint ein Requester, in dem
  200.            abgefragt wird, in wieviel Schritte der Regler unterteilt
  201.            werden soll (Default: 16).
  202.            (z.B. RGB-Farbregler)
  203.   Abkürzung: X
  204.  
  205.   - Vert: Wie Horiz, nur Vertikal!
  206.   Abkürzung: Y
  207.  
  208.   - Both: Erstellen eines zweidimensionalen Proportional-Gadgets.
  209.           (z.B. Screen-Position-Gadgets in den Preferences)
  210.   Abkürzung: Z
  211.  
  212. Der Rahmen eines Proportional-Gadgets wird von Intuition automatisch
  213. gezeichnet und kann vom Benutzer nicht geändert werden!
  214.  
  215.  
  216. ATTRIBUTES-Menü:
  217. ----------------
  218. Für alle folgenden Requester gilt, daß das betätigen des Close-Gadgets
  219. des Requester-Windows die Funktion ohne Änderung abbricht.
  220.  
  221. - Text: Versieht ein Gadget mit einem Text oder ändert einen bereits
  222.         vorhandenen Text.
  223.         Nach Auswahl des Gadgets erscheint ein Requester mit folgenden
  224.         Feldern:
  225.         Text:     Text des Gadgets
  226.         frontPen: Schriftfarbe
  227.         backPen:  Hintergrundfarbe
  228.         Center:   Zentrieren des Textes im Gadget (für Boolean-G.).
  229.         Position: freie Wahl der Position des Textes.
  230.     Falls das gewählte Gadget ein String-Gadget ist, wird das Text-
  231.     Gadget des Requesters nicht automatisch aktiviert.
  232.   Abkürzung: F9
  233.  
  234. - Border:
  235.   - No: Alle neuen String- und Boolean-G. werden ohne Rahmen erstellt.
  236.   Abkürzung: <RAMIGA>O
  237.  
  238.   - Single: ... mit einfachem Rahmen erstellt.
  239.   Abkürzung: <RAMIGA>I
  240.  
  241.   - Double: ... mit doppeltem Rahmen erstellt.
  242.   Abkürzung: <RAMIGA>D
  243.  
  244. - String-Ausrichtung:
  245.   - Left: Alle neuen String-G. sind linksbündig bei der Eingabe.
  246.   Abkürzung: <RAMIGA>E
  247.  
  248.   - Center: ... zentrieren bei der Eingabe.
  249.   Abkürzung: <RAMIGA>C
  250.  
  251.   - Right: ... sind rechtsbündig bei der Eingabe.
  252.   Abkürzung: <RAMIGA>R
  253.  
  254. - Change Attributes:
  255.   Ändern der Attribute (Rahmen, Ausrichtung...) eines bestehenden
  256.   Gadgets. Je nach Typ des gewählten Gadgets erscheinen folgende
  257.   Requester:
  258.  
  259.   - String-Gadget: Ändern eines String/Integer-Gadgets.
  260.     Auswahl:
  261.     Max. Textlength: Max. Anzahl einzugebender Zeichen
  262.     Type of Gadget:  Umschalten Normal/Integer
  263.     Alignment:       Ändern der Ausrichtung
  264.     Border:          Ändern des Rahmens
  265.  
  266.   - Boolean-Gadget: Ändern eines Boolean/toggleSelect-Gadgets.
  267.     Auswahl:
  268.     Type of Gadget: Umschalten Normal/toggleSelect
  269.     Border:         Ändern des Rahmens
  270.  
  271.   - Proportional-Gadget:
  272.     Auswahl:
  273.     Number of steps in x-direction: Anzahl Schritte in x-Richtung
  274.     Number of steps in y-direction: Anzahl Schritte in y-Richtung
  275.   Abkürzung: F10
  276.  
  277.  
  278. --------------------------------------
  279. Beschreibung des erstellten Quellcodes
  280. --------------------------------------
  281. Den Quelltext einer Gadget-Struktur erstellt man durch die
  282. "MakeModule"-Funktion im PROJECT-Menü.
  283.  
  284. Es werden ein DEFINITION- und ein IMPLEMENTATION-Module erstellt.
  285. Der Name des Moduls ist der Name, der beim Erstellen durch
  286. MakeModule angegeben wurde.
  287. Beispiel: Filename ist: "DF1:Projekt/Requester". Dann werden die
  288.           Files "Requester.def" und "Requester.mod" erstellt und
  289.           im Directory "DF1:Projekt" abgelegt.
  290. Diese Module importieren nur aus Standard-Bibliotheken, sind also
  291. völlig unabhängig von diesem Projekt.
  292.  
  293. Im folgenden steht <Name> für den Modulnamen.
  294.  
  295. Im Definition-Module wird zur Verfügung gestellt:
  296. - die Konstante "NumbGadg<Name>". Sie enthält die Anzahl der von diesem
  297.   Modul erstellten Gadgets.  (Bsp: "CONST NumbGadgRequester = 8;")
  298.  
  299. - die Prozedur "Init<Name>". Sie erstellt wahlweise ein Window mit der
  300.   im Editor festgelegten Größe und Position und den Gadgets oder baut
  301.   die Gadgets in ein bestehendes Window ein. Ersteres Window hat das
  302.   Close-Gadget, ist verschiebbar und hat die Tiefen-Gadgets. Die
  303.   IDCMP-Flags sind gadgetUp, gadgetDown und closeWindow. Der Titel
  304.   des Windows und der Screen, in dem es liegen soll, kann angegeben
  305.   werden.
  306.   Alle Gadgets haben die ActivationFlags "relVerify" und "gadg-
  307.   Immediate".
  308.   Parameter:
  309.      (VAR wptr   : ADDRESS;
  310.           Screen : ADDRESS;
  311.           Title  : ADDRESS);
  312.  
  313.   Falls "wptr=NIL" übergeben wird, wird das Standard-Window wie oben
  314.   beschrieben erstellt und in "wptr" der WindowPtr darauf zurückgegeben.
  315.   In "Screen" kann ein Zeiger auf den Screen, in dem das Window er-
  316.   scheinen soll, und in "Title" die Adresse des Windowtitels übergeben
  317.   werden. Falls "Screen=NIL", wird das Fenster im Workbench-Screen
  318.   eröffnet.
  319.  
  320.   Falls in "wptr" ein gültiger WindowPtr übergeben wird, werden die
  321.   Gadgets in dieses Window eingebaut. wptr wird nicht verändert.
  322.   "Screen" und "Title" haben dann keine Wirkung.
  323.  
  324.   (Bsp: PROCEDURE InitRequester
  325.                                (VAR wptr   : ADDRESS;
  326.                                     Screen : ADDRESS;
  327.                                     Title  : ADDRESS);
  328.         Aufruf z.B. mit:
  329.           WPtr := NIL;
  330.           InitRequester (WPtr,NIL,ADR("Window-Titel"));
  331.         eröffnet das Standard-Window mit dem Titel "Window-Titel" im
  332.         Workbench-Screen.)
  333.  
  334. - die Prozedur "Close<Name>". Sie schließt das von "Init<Name>" er-
  335.   öffnete Window wieder.
  336.   Parameter:
  337.      keine
  338.  
  339.   !! ACHTUNG: die Prozedur verwendet das normale "Intuition.CloseWindow"
  340.      zum Schließen des Windows. Diese Prozedur darf NICHT verwendet
  341.      werden, wenn sie ein eigenes Window verwenden und dieses vom
  342.      "Windows"-Modul des M2Amiga-Compilers erstellt worden ist.
  343.      So ein Window MUß auch von "Windows.CloseWindow" wieder geschlossen
  344.      werden, sonst gibt es einen Guru am Programmende.
  345.      (So was sollte eigentlich auch im Handbuch des Compilers erwähnt
  346.       sein!)
  347.  
  348.   (Bsp: PROCEDURE CloseRequester;
  349.         Aufruf:
  350.           CloseRequester;)
  351.  
  352. - die Prozedur "Get<Name>GPtr". Sie liefert den GadgetPtr des Gadgets
  353.   mit der angegebenen ID.
  354.   Parameter:
  355.     (ID : INTEGER) : ADDRESS;
  356.  
  357.   Der Bereich der IDs geht von 0 bis "NumbGadg<Name>"-1.
  358.   Eine Bereichsüber/unterschreitung führt zu einem Laufzeitfehler.
  359.  
  360.   (Bsp: PROCEDURE GetRequesterGPtr (ID : INTEGER);
  361.         Aufruf z.B.:
  362.           GPtr := GetRequesterPtr(NumbGadgRequester-1);
  363.         liefert den GadgetPtr des letzten Gadgets.)
  364.  
  365. - Eine Liste der Gadgets mit ID, Typ und Text.
  366.   Aus dieser Liste, die ein Kommentar im Quelltext ist, entnimmt man,
  367.   welches Gadget welche ID hat, über die allein das Gadget identifi-
  368.   ziert werden kann.
  369.   Die Reihenfolge der IDs hängt von der Erstellungsreihenfolge ab.
  370.   Das zuerst erstellte Gadget erhält die ID 00, das zuletzt Erstellte
  371.   immer die höchste ID (= NumbGadg<Name> - 1). Wird ein Gadget ge-
  372.   löscht, rücken die Folgenden nach.
  373.  
  374.   (Bsp:
  375.    ID  Typ         Text des Gadgets
  376.    ---------------------------------------------------------
  377.    00  boolGadget  OK
  378.    01  strGadget   Name:
  379.    02  strGadget   Adresse:
  380.   )
  381.  
  382. Es wird keine Prozedur zur Abfrage der Gadgets erstellt. Dies bleibt dem
  383. Anwender überlassen. Das "Gadgets"-Modul dieses Projekts eignet sich
  384. aber gut dazu.
  385.  
  386.  
  387. ----------
  388. Sonstiges:
  389. ----------
  390.  
  391. Die Erstellung dieses, wie ich meine sehr nützlichen, Projektes hat ins-
  392. gesamt ca. 4 Monate gedauert (mit Unterbrechungen).
  393. Ich habe es trotz dieses Aufwands als Public Domain deklariert, da ich es
  394. zuerst nur für den Eigengebrauch geschrieben habe und mir erst später
  395. gesagt habe, daß eigentlich nichts gegen eine Veröffentlichung spricht.
  396.  
  397. Ich bitte hiermit trotz des Public-Domain-Status alle regelmäßigen An-
  398. wender des Projekts um eine Honorierung der Arbeit, die ich mit diesem
  399. Projekt hatte, und der Zeitersparnis, die man mit diesem Projekt bei
  400. der Programmierung hat. Dieser Betrag sollte im Bereich von 5 bis 20.-DM
  401. liegen.
  402.  
  403. Jeder, der schon einmal eine größere Gadget-Struktur "von Hand"
  404. programmiert hat, weiß von dieser ziemlich nervtötenden Arbeit ein Lied
  405. zu singen, und sollte sich einmal überlegen, wie lange er ohne dieses
  406. Projekt dafür gebraucht hätte.
  407.  
  408. Außerdem hatte ich durch die Veröffentlichung in der Amok-Reihe auch ein
  409. paar Unkosten (Porto, Shareware für Menugenerator) und ich würde gern
  410. wenigstens diese Kosten wieder hereinbekommen, auch um einen Anreiz zu
  411. bekommen, das Programm weiterzuentwickeln und wiederum zu veröffent-
  412. lichen.
  413.  
  414. Vielen Dank im voraus.
  415.  
  416.  
  417. Mögliche oder geplante Erweiterungen:
  418. -------------------------------------
  419. - gespeicherte Strukturen mit Icons
  420. - Von den Gadgets unabhängige Texte und Rechtecke im Window plazieren
  421. - erstellter Quellcode verwendet wahlweise das "Gadgets"-Modul, um
  422.   kürzeren Code zu erstellen.
  423. - Nicht ein Window mit Gadgets, sondern einen "echten" Requester
  424.   erstellen.
  425. - mehr verschiedene Rahmentypen
  426. - Farbwahl für Rahmen
  427. - Einbau eines Menügenerators  (etwas utopisch)
  428. - Unterscheidung NTSC/PAL. Bisher wird PAL verwendet.
  429.  
  430. Probleme und Hinweise:
  431. ----------------------
  432. - Das Programm ist verdammt groß geworden (ein optimierender Linker
  433.   sollte zum Standardumfang des Compilers gehören!). Das Programm
  434.   läuft bei 512K RAM, aber manche der geplanten Erweiterungen würden
  435.   das Programm noch erheblich vergrößern. Und wenn man dabei auch noch
  436.   den Compiler resident halten möchte...
  437. - Um die sym-Files klein zu halten, wurden die meisten Ptr-Typen
  438.   (GadgetPtr,WindowPtr,...) durch den Typ ADDRESS ersetzt. Aus dem
  439.   Bezeichner oder der Beschreibung geht jeweils hervor, welcher
  440.   Typ gemeint ist.
  441. - Selbst kleinere strukturelle Änderungen ziehen eine Änderung der
  442.   zentralen Datenstruktur und somit des Abspeicherungsformats nach sich.
  443.   Es wird dann schwierig werden, Kompatibilität zu erhalten, wenn
  444.   verschiedene Leute verschiedene Änderungen machen.
  445. - Bei der Bearbeitung von String-Gadgets treten immer wieder kleinere
  446.   Probleme damit auf, daß durch das Anwählen des Gadgets dies aktiviert
  447.   wird und bleibt (Wer weiß, wie man es vom Programm her ausschaltet?).
  448.   Beim Löschen eines String-G. bleibt z.B. der Cursor vorerst an der
  449.   alten Stelle.
  450.   Diese Probleme sind meist graphisch und lassen sich durch Anklicken
  451.   des Windows beheben (führt zum Neuaufbau). Abstürze sind auch bei
  452.   größeren Strukturen sehr selten geworden.
  453.  
  454. ---------------------------------------------------------------------------
  455. Ende GadgetEd.dok
  456. letzte Änderung: 13.01.1991   Hubert Bildstein
  457. ---------------------------------------------------------------------------
  458.